                                File format
                                -----------
Commands to define file
-----------------------
Commands followed by one or more spaces (case insensitive) :
APP        Application name
IN      *  Input file (or - for new file) - Must preceed OUT
           If preceeded by *, the module whose name is given will be
           extracted from memory and processed.
OUT     *  Output file
TYPE    *  Type of file (Default = Module)
VER        Sets the version of the code. This will be auto-incremented on
           each assembly. It should be in the form 1.00a 
MAX        Maximum amount of memory to reserve in bytes (or suffix with K)
PC         Start PC for file if not default
DEFINE     Define that file with advanced definition
PRE        Start preassembly lines
{          Start comment (non-embeddable must be start of line)
}          End comment (must be start of line)

        * commands which must be included
Command lines terminate at . labels, # commands or @ pc setting command.
If filenames are not full paths then the same path as the patch file is
assumed.


Filetypes
---------
Module     Relocateable module (base PC=&0)
Util       Utility program (base PC=&0)
Utility    Ditto
Absolute   Absolute code with header (base=&8000)
Code       Direct code (base PC arbitrary), no type
Memory     Stored directly into memory, ie no output file
AOFModule  AOF file with module header
AOF        AOF file


Preassembly lines
-----------------
These are lines which will be added verbatum to the program. Use this to add
variable definitions and any procedure calls to initialise things.
End with END PRE on a line of its own.


Further definition using DEFINE
-------------------------------
Module    Allows full definition of the module header. Use only if a new file
          is being created. Dependant upon filetype being Module
Workspace Allows definition of workspace offsets for use with workspace
          instructions. Usually used in modules
Macros    Allows definition of macro commands, currently being developed and
          should be /used with caution/.
          

Further definition using DEFINE MODULE
--------------------------------------
Commands followed by one or more spaces (case insensitive) :
NAME       Module name as used in *Modules command (default=Untitled)
VERSION    Version number to use in help string (default=1.00)
AUTHOR     Author name to use in help string (default=not used)
HELP       Help name to use in *Help Modules (default=<NAME>)
INIT       Module initialisation address or label (default=no code)
FINAL      Module finalisation address or label (default=no code)
START      Module start address or label (default=no code)
SWIHANDLER Module swi handler code (default=handled automatically)
SERVICE    Module service code (default=no code)
SERVICES   Begin service definition
VECTORS    Begin vector definition
EVENTS     Begin event definition
COMMANDS   Begin OSCLI/Help/Configure commands definition
SWIS       Begin SWI call definition
WORKSPACE  Length of workspace to claim in r12, prefix with * to initialise 0
WIMPSWIS   Begin WimpSWIVe handler definition (WimpSWIVe  Andrew Clover)
PREFILTER  Begin a Pre-Poll filter
POSTFILTER Begin a Post-Poll filter
END MODULE Terminate parsing of further defintion

Service commands
----------------
The service block should be structured as :
  <service> <spaces> <code>
and end with :
  End Services


Vectors commands
----------------
The vectors block should be structured as :
  <vector> <spaces> <code>
and end with :
  End Vectors


Events commands
----------------
The events block should be structured as :
  <event> <spaces> <code>
and end with :
  End Events


OSCLI commands
--------------
Commands followed by one or more spaces (case insensitive) :
NAME      Command/Help/Configure name (must preceed all entries)
CODE      Address of code or label (default no code)
MAX       Maximum number of parameters (default=0)
MIN       Minimum number of parameters (default=0)
TYPE      Type of command (default=command)
          Options : FILING,FS            Filing system command
                    CONFIG,CONFIGURATION Configure command
FLAGS     Value of flags (overrides MAX, MIN and TYPE settings)
SYNTAX    Syntax of command definition (default no message)
          If ... then multi-line syntax follows (should be indented)
          Terminate multi-line syntax by reducing indentation
HELP      Help on command (default no message)
          If ... then multi-line help follows (should be indented)
          Terminate multi-line help by reducing indentation
END COMMANDS  Terminate command definition


SWI commands
------------
Command followed by one or more spaces (case insensitive) :
BASE     Set base of SWI commands
PREFIX   Set prefix of SWI commands
END SWIS Terminate definition of SWI commands
All other commands are treated as follows :
  SWI number followed by spaces,
  SWI alias followed by spaces,
  SWI code or label,
  Return
Example :
 SWIs
  Base     &400c0
  Prefix   Wimp
   0    Initialise    swi_initialise
   1    CreateWindow  swi_createwin
 End SWIs
 

WimpSWI commands
----------------
Command followed by one or more spaces (case insensitive) :
SWI          Set Wimp SWI name to handle
PRE          Pre-handler code
POST         Post-handler code
END WSWIS    Terminate definition of WimpSWIve handlers
END WIMPSWIS ditto

Pre-, or post-handler code may be preceeded by a ^ symbol to make the code
high priority. Mixed priority SWI handlers are not allowed. Use two seperate
definitions.


Filter commands (both pre and post)
---------------
Command followed by one or more spaces (case insensitive) :
NAME           Name for filter (as passed to FilterManager)
CODE           Handler code
MASK           Mask for post-filter (N/A in Pre-filter)
ACCEPT         Alternative format for specifying mask
TASK           Task to apply filter to (or - for all tasks)
END FILTER     Terminate definition of Filter handler
END PREFILTER  Terminate definition of Filter handler (only in pre-filter)
END POSTFILTER Terminate definition of Filter handler (only in post-filter)

The post-filter requires that either MASK or ACCEPT be specified. ACCEPT may
be passed a number of descriptions to give the reason codes it will accept.
These can either be entered with or without, but are case sensitive :
 Primary name     Secondary name            Tertiary name
 --------------------------------------------------------
 Null
 Redraw
 OpenWindow
 CloseWindow
 PointerLeaving
 PointerEntering
 MouseClick
 UserDragBox      DragDropped
 KeyPress         KeyPressed
 Menu             MenuSelection
 Scroll           ScrollRequest
 LoseCaret
 GainCaret
 PollWord
 UserMsg          UserMessage               Message
 UserMsgRec       UserMessageRecorded       MessageRec
 UserMsgAck       UserMessageAcknowledged   MessageAck

Any of these names may be given, and multiple entries should be given over
lines, using the command ACCEPT each time.


Further definition using DEFINE WORKSPACE
-----------------------------------------
Commands followed by one or more spaces (case insensitive) :
NAME          Sets the name of the area so that it may be alternatly mapped
              later.
PREFIX        Sets the prefix for all variables in this block, which will be
              placed after any ` characters at the start of the variable
              name.
DEFAULT       Sets the register that the area is mapped to by default, and
              after being restored.
END WORKSPACE Terminates definition of workspace parameters.

It is recommended that variables in the workspace are prefixed by the `
character to enable easy identification, although this is not necessary.
All other lines are treated as follows :
  Variable name followed by a number of spaces, then an identifier for the
  type, then a repitition count. If the variable is prefixed by = then the
  pointer is word aligned.
  eg. `address   !7
or
  Byte offset (Dec or Hex prefixed by &) optionally prefixed by ! to denote word
offset followed by a number of spaces, then an identifier.

These can be suffixed with any comment you require as the rest of the line is
ignored. To repeat a set of data pointers use ( as the first character to
start, and ) to end followed by a repetition count. If the repitition count
is not used then it is assumed to be 1. Unions (as C) may be defined by using
| within the repeat structure. Such unions should be of the same length or
longer. No error will be raised if the sections are unequal.

Valid identifiers are :
  !  integer word
  %  single byte
  $  string (reptition count is number of characters to reserve space for
     including terminator)
  ^  Structure reference. The referenced structure will be repeated the
     number of times specified.

The length of a structure is assigned to the variable `len_name where name is
the name assigned to the structure. If no name is given then the name is
assumed to be ws_ plus the number of the block starting at 0.

Example :
Define Workspace
  Name      zap_vars
  Default   r12
    !0  scn_xos   Screen horizontal size (in os coords)
    !1  scn_yos   Screen vertical size (in os coords)
    !2  opt_flags Config file flags word (see E-Flags)      
  
  Name      OS_Box
  Prefix    box_
  Default   r10
    `x0   !   Left of box
    `y0   !   Bottom of box
    `x1   !   Right of box
    `y1   !   Top of box       ; } These will be refered to as `box_x0, etc
  
  Name      Wimp_IconData
  Prefix    Wimp_IconData_
  Default   r10
    extent     ^OS_Box        Area of icon
    flags      !              Icon flags
    text       $12            Text string
    
  Name      Wimp_Window
  Prefix    Wimp_Window_
  Default   r9
    visible    ^OS_Box        Visible area of box
    xscroll    !              Horizontal scroll offset
    yscroll    !              Vertical scroll offset
    next       !              Next window up stack
    flags      !              Window's flags
    title_fg   %              Foreground colour
   <excerpt missing>
    xmin       %2             Horizontal minimum of window
    ymin       %2             Vertical minimum of window
    title_data ^Wimp_IconData Title icons data
    icons      !              Number of icons in window
    (
     icon_data  ^Wimp_IconData   Icon space
    ) 32

End Workspace
    
Further definition using DEFINE MACROS
-----------------------------------------
Commands followed by one or more spaces (case insensitive) :
COMMAND       Sets the name of the macro. This should be the first line of
              a macro.
CONDS         Sets the conditionals that may be used with this macro. The
              standard 16 conditions are accepted, as well as :
              ALL for all conditionals
              NEVER for no conditionals
              INVERT for exclusion conditionals; jump over code will be
              inserted for the reverse conditional.
TEMPS         Sets the number of temporary registers which may be used (N/A)
MASK          Sets the parameter mask for the instruction
CODE          Defines the actual code to insert
END CODE      Ends a code definition
END MACROS    Terminates definition of macros

Macro mask values
-----------------
The macro mask tells the pre-processor what type of instruction to accept.
Usually this is just a comma seperated register list. The mask must be
adhered to quite stringently, and if errors will be raised if you do not use
the correct syntax. The format is :
  @rx  Normal register, use @rx in code to reference register. x can be any
       one character
  @gx  Any group of registers, in the multiple register format. x can be any
       one character
  @cx  Constant. NOT IMPLEMENTED YET
  @ax  Address. NOT IMPLEMENTED YET
  @sx  String. NOT IMPLEMENTED YET

Macro code
----------
The macro code itself will be inserted into the users code at the relevant
point, possibly prefixed by an exclusion instruction. Within the code,
certain macros may be used :
  @rx  Insert register from parameter list
  @gx  Insert group of registers from parameter list
  @t#  Temporary register, if specified in definition. (NOT IMPLEMENTED YET)

Local variables are allowed and will be embedded such that multiple macros
may be used and the variables remain local to the current macro. You can use
non-local references, but this is not advised.

If you wish to reference a non-macro local variable you should use $$ as the
variable prefix (instead of just $ as this would be recognised as a
macro-local variable). This will not jump up one level of macros, but out of
the macro chain completely. It is unlikely that you will need to use this
'feature' unless you are writing thread checking code or something similar.


Actual Assembly
---------------
First character of line defines action :
 %   Literal.
     Rest of line is entered verbatum to program (outside assembly)
 @   New PC.
     Change value of program counter (only really valid during editing)
     Can use endofcode to represent the word after the last byte in the
     file originally.
 #   Pre-assembler directive.
     See below
 {   Start comments
     Comments are non recursive and terminated by } on start of line

All other lines are passed verbatum to assembler


Pre-assembly directives
-----------------------
Directives consist of command followed by its arguments :
LOAD     Load a file. Parameters seperated by commas.
         Parameters : Filename, Length
REM      Enable/Disable remarks.
         Parameters : ON, TRUE, ENABLED
                      OFF, FALSE, DISABLED
POST     End main code. No parameters.
         Code that follows will be appended to file before END command.
         Use this for anything to be done after the code is assembled, such
         as running the resultant code.
COND     Conditional assembly command. Variable parameters.
         See below
END      End main code. No parameters.
         Code that follows will be appended to file.
         Use this to include macro FuNctions or PROCedures
CHECK    Check that particular sections of the input file are set to certain
         values.
         See below.
LIBRARY  Install library routines.
         See below.
INCLUDE  Include a file at the end of the code.
         The file named will be included as if it were contained after the
         last line of this file (or the last included file.) This operation
         may change in future.
HERE     Locate various objects.
         See below
MAPWS    Map workspace to register.
         Parameters : Block,register. If register omitted then restore default


Conditional assembly directives
-------------------------------
Directives consist of the COND pre-assembler directive and a number of
possible suffixes. All conditional assembly is, by default, a pre-assembly
process, and so the assembled code will consist of only the code to be
assembled. By specifying INLINE, all the code will be assembled, the
conditionals only being evaluated at run-time.

Conditional structures may be embedded, currently to a depth of 10 levels.
This should be sufficient for most purposes. The conditional values should be
set up at the very start of the code, preferably in the PRE section of the
code. The form of conditional assembly (INLINE or EXTERNAL) should be set
prior to this.
  
Directives are :
COND INLINE
         Code will be assembled in-line, rather than pre-processed to remove
         redundant code.
COND EXTERNAL
         Code will be pre-processed to remove the redundant code.
COND SET condition_name boolean
         Set the condition named to the value stated.
COND condition_name question_to_ask
         Set conditional assembly flag
         Set the condition flag named, dependant on the users input in
         response to the question. If INLINE, the question will be asked in a
         command window, otherwise the question will take the form of a
         Message box.
COND OF condition_name
         Start conditional assembly structure.
         The following code will be assembled if condition_name is TRUE.
COND ELSE
         ELSE clause in conditional structure.
         If the previous condition was FALSE, and all higher conditions are
         TRUE, then the following code will be assembled.
COND END or COND ENDIF
         End of conditional assembly structure.
         All following code will be assembled normally, according to higher
         conditional code.


Check directives
----------------
These are used to test if the input file is the correct version and has had
no changes made to it.
Directives are :
CHECK STRING address string
         Check that the address stated has a ctrl-terminated string set to
         that specified. To ensure that the string is correct it may be
         enclosed in quotes. These are ignored, but set the bounds of the
         string so spaces may be included at either end.
CHECK WORD address value
         Check that the address stated is set to the value given. The value
         may be any value acceptable by the Basic evaluation functions.
CHECK LEN length
         Check that the length of the input file is that given. The value
         may be any value acceptable by the Basic evaluation functions.


Library files
-------------
These are used to embed lines which are likely to be common to many
programs. The syntax is :
  LIBRARY "filename",[#]routine[[.routine].routine] (etc)
filename is absolute if there is a path, otherwise it is searched for in the
Libraries directory in JFPatch.
routine may be * if all routines are to be installed.

Library files consist of the first line Library name, where name is the name
of the library to be used in reporting errors and in the basic program.
Actual routines are noted by the first character on a line being a . and the
next character not being ` or _. It is assumed that ` labels are used for
data labels, and _ for loop or internal labels within routines.

In library files local labels may be used, but care must be taken if the
routine is to be embedded in another routine instead of standing alone as is
intended.

Library files are not embedded where the LIBRARY directive is located, unless
the first routine is preceeded by a hash (#), in which case all prior LIBRARY
routines including this definition are embedded at this point.

Otherwise, it is necessary to use the HERE directive to locate the libraries.


Here directives
---------------
The Here directive locates the position of various objects within the code.
The directives are :
FOOTER    Embed a mark indicating the end of the file.
          Usually this will be located after all code, and before any Post
          directives, although it could occur anywhere. The usual text is
          End of file, although by saving a file into the JFPatch directory
          called Footer, the line may be altered (note only one line is
          allowed)
LIBRARIES Embed all prior libraries at this point.
          Usually this will be located at the end of the file.


Post-assembly directives
------------------------
Directives consist of command followed by its arguments :
RUN      Run the file specified. If the file is <CODE> then run the
         output file. <THISDIR> specifies the directory the patch file is in.
WIMPRUN  Filer_Run the file specified. If the file is <CODE> then run
         the output file. <THISDIR> specifies the directory the patch file is
         in.
EXAMINE  Examine the area of memory specified. The area will be saved to a file
         and loaded as a text file. The area may be specified by start and
         length (using +), or by start and end.
CAPTURE  Capture all subsequent output. The output is merely Spooled to a file,
         and before the END statement is turned off. A parameter may be used to
         indicate whether capture is enabled or not.
END      End main code. No parameters.
         Code that follows will be appended to file.
         Use this to include macro FuNctions or PROCedures


Assembly macro instructions
---------------------------
Use as normal assembler instructions (eg LDR, or macro ADR) :
LADR##  Long ADR (range 64k).
        Parameters : register, address or label
        Eg. LADRVS  r0,`error_message    ; if V set, get error message

XSWI##  eXtended SWI (gives register values)
XBL##   eXtended BL (gives register values)        
        Parameters : SWI name or address or label, r0, r1, r2, r3, etc
        Prior to the SWI or BL code, MOV (or LMOV) instructions will be
        assembled to set the appropriate registers up. This is done
        cronologically, so reverse references must be avoided.
        You can preceed a number with a # to use a MOV where you have used a
        variable. Preceeding a reference by ^ will use ADR to get's it's
        address.
        Eg. XSWI   "XOS_Byte",148,0,65       ; insert A into buffer

XLDMFD  eXtended LoaD from Full Descending stack (restore all bar r0)
        Parameters : (as LDM, except always write-back, and no restore flags)
        If the oVerflow flag is set (VS) then the LDM will be made without
        restoring r0 from the stack. This is so that errors may be preserved
        at the exit of a routine.
        Eg. XLDMFD  (sp)!,{r0-r5,pc}         ; Return from call (with error)
        The actual code assembled is :
           ADDVS   $r1,$r1,#4
           LDMVSFD ($r1)!,$<regs exc. r0>
           LDMFD   ($r1)!,$<regs>
        
REM     REMark (removable).
        Parameters : Text string to print
        Format of string :
          %%   display % symbol
          %r#  display register # in decimal (# is a hex number)
          %&#  display register # in hex (# is a hex number)
          %a#  display register # as ascii
          %E#  display error at register #
          %$#  display string pointed to by register # (# is a hex number)
          %R   display all registers
          %I   ignore (used to embed control strings)
          %C   no CR-LF
          %c## ctrl code embedding (## in decimal)
        Message will be followed by CR-LF unless %C specified. If Streaming
        is enabled then all REM based messages will be sent to the Stream,
        including REMP.
        Eg. REM "Iteration count : %r7, time taken %r0"

REMP    REMark (Permanant).
        As REM, but not removed by REM Off.

ERR     Generate ERRor.
        Parameters : Error string
        Mainly for testing, do not use in distributed code
        Eg. ERR  "Erm, somethings gone wrong - I can't seem to find my head"
        
DIV     DIVide one register by another.
        Parameters : Top, Bottom
        Result is returned in Top. Note: Large amounts of code will be
        assembled!
        Eg. DIV   r0,r1
        
RES     REServe space.
        Parameters : Space needed
        Eg. RES   16          ; reserve space for enumerated task block
        
LMOV##  Long MOV
        Parameters : Register, #value
        This now copes correctly with -ve numbers and should assemble any
        32-bit value using the least number of instructions!
        Eg. LMOVEQ  r0,#&124

LADD##  Long ADD
        Parameters : Register, Register, #value
        Eg. LADDHI  r1,r12,#&12343

MODE##  Set processor MODE
        Parameters : Mode
                or : Mode, register 1, register 2
        Mode may be USR, FIQ, IRQ or SVC. Registers 1 and 2 are optional, and
        if omitted r8 and r9 respectively are used (as recommended in Acorn
        guidelines for resetting processor mode to SVC).
        Register 1 holds the modified flags, register 2 the original flags.
        The actual code assembled is :
          MOV##  $r2,pc:ORR##  $r1,$r2,#3:TEQ##P  $r1,#0:MOV##  r0,r0
        To store r14_svc as recommended by Acorn, the correct code is given by
        an extended subset of the MODE macro:

MODE##  xSVC
        Preserve/Restore r14_link
        Parameters : Mode, register 1, register 2, register 3
                or : Mode, register 1, register 2
                or : Mode, register 3
                or : Mode
        Mode may be +SVC or -SVC. Registers 1 and 2 are the temporary
        registers as above, and default to r8 and r9 respectively.
        Register 3 is the location to stack the link register, and defaults
        to r14. The stack used is a Full Descending stack.
        The code assembled is :
        
        For +SVC
          MOV##   $r2,pc
          ORR##   $r1,$r2,#3
          TEQ##P  $r1,#0
          MOV##   r0,r0
          STM##FD ($r3)!,{link}
          
        For -SVC
          LDM##FD ($r3)!,{link}
          TEQ##P  $r2,#0
          MOV##   r0,r0


LDRW##  LoaD Register in Workspace
STRW##  STore Register in Workspace
LDRBW## LoaD Register as Byte in Workspace
STRBW## STore Register as Byte in Workspace
        Parameters : register, workspace label
        This will produce the correct code to load the parameter required
        using the registers mapped to the block, or default if none is
        mapped.
        The resulting code is LDR##[B] rx,[ry,#label]
        Eg. LDR r0,`win_minx

ADRW##  ADdRess in Workspace
        Parameters : register, workspace label
        The address of the workspace location is found from the mappings
        specified, or the default if none is set.
        Eg. ADR r0,`win_iconblock

SWAP##  Swap two registers around
        Parameters : register 1, register 2
        The two registers will be swapped, conditionally if specified. The
        actual code produced is :
           EOR##   0,0,1
           EOR##   1,0,1
           EOR##   0,0,1
        
GETBIT  Get a bit from a block
        Parameters : Bit, Address or label
        Returns bit state in Z, ie EQ if set

SETBIT  SET a BIT in a block
CLRBIT  CLeaR a BIT in a block
        Parameters : Bit, Address or label

SETx##  SET flag x   } x = Z (Zero), N (Negative)
CLRx##  CLeaR flag x }     V (oVerflow), C (Carry)
        Parameters : Temporary register (optional)
        If not specified, the link register will be used as the temporary
        register.
        Eg. SETVEQ  r9

EQUZ    EQUate Zero suffixed string
        Parameters : String
        String will be assembled as EQUS <string>+CHR$0
        Eg. EQUZ "Hello there"
EQUZA   EQUate Zero suffixed string, then align
        Parameters : String
        String will be assembled as EQUS <string>+CHR$0 then ALIGN
        Eg. EQUZA "Hello there"

NOP##   No OPeration
        No parameters
        Assembles MOV## r0,r0. Mostly for use in re-sync of register banks,
        although this is performed within the MODE instruction.
        
Instructions suffixed by ## may have conditionals appended to them.


Variables
---------
Many of the variables used in the creation of the code by the intermediate
Basic program are available for use by you. Others, however, are reserved.
Those which are available, or of interest, are :
 pass%     Current assembler pass (usually 4 or 6)
 sp        Stack Pointer (value = 13)
 link      Link Register (value = 14)
 pc        Program Counter (value = 15)
 vbit      Overflow flag value (value = 1<<28)
 cbit      Carry flag value (value = 1<<29)
 zbit      Zero flag value (value = 1<<30)
 nbit      Negative flag value (value = 1<<31)
 P%        Assemble as pointer
 O%        Assemble to pointer
 endofcode Pointer to address of next free location after last byte of code
           loaded
 patchdir$ Name of the directory in which the source exists
 outfile$  Filename of the output file
 infile$   Filename of the input file
 MC%       Base of machine code assembly area

However, the following variables should never be used in source code :
 module_*  }
 _mod_*    } When the Module definition is used various variables are
 mod_*     } assigned when the code is created. For this reason, unless you
 `mod_*    } are very careful with what you are entering.
 `module_* }
